<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
 <head>
  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  <title>Executes an SQL query passed as a prepared statement, with a 
   list of values to substitute for placeholders, and return the 
   results as a normalised data graph.</title>

 </head>
 <body><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="sdo-das-relational.createrootdataobject.html">SDO_DAS_Relational::createRootDataObject</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="sdo-das-relational.executequery.html">SDO_DAS_Relational::executeQuery</a></div>
 <div class="up"><a href="ref.sdodasrel.html">SDO-DAS-Relational 函数</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="sdo-das-relational.executepreparedquery" class="refentry">
 <div class="refnamediv">
  <h1 class="refname">SDO_DAS_Relational::executePreparedQuery</h1>
  <p class="verinfo">(^)</p><p class="refpurpose"><span class="refname">SDO_DAS_Relational::executePreparedQuery</span> &mdash; <span class="dc-title">
   Executes an SQL query passed as a prepared statement, with a 
   list of values to substitute for placeholders, and return the 
   results as a normalised data graph.
  </span></p>

 </div>

 <div class="refsect1 description" id="refsect1-sdo-das-relational.executepreparedquery-description">
  <h3 class="title">说明</h3>
  <div class="methodsynopsis dc-description">
   <span class="type"><span class="type SDODataObject">SDODataObject</span></span> 
   <span class="methodname"><strong>SDO_DAS_Relational::executePreparedQuery</strong></span>
    ( <span class="methodparam">
    <span class="type"><a href="class.pdo.html" class="type PDO">PDO</a></span>
     <code class="parameter">$database_handle</code>
   </span>
   , <span class="methodparam">
    <span class="type"><a href="class.pdostatement.html" class="type PDOStatement">PDOStatement</a></span>
     <code class="parameter">$prepared_statement</code>
   </span>
   , <span class="methodparam">
    <span class="type">array</span>
     <code class="parameter">$value_list</code>
   </span>
   [, <span class="methodparam">
    <span class="type">array</span>
     <code class="parameter">$column_specifier</code>
   </span>
  ] )</div>


  <div class="warning"><strong class="warning">Warning</strong><p class="simpara">此函数是<em class="emphasis">实验性</em>的。此函数的表象，包括名称及其相关文档都可能在未来的
PHP 发布版本中未通知就被修改。使用本函数风险自担 。</p></div>

  <p class="para">
   Executes a given query against the relational database, 
   using the supplied PDO database handle.
   Differs from the simpler 
   <span class="function"><strong>executeQuery()</strong></span>
   in that it takes a prepared statement and a list of values.
   This is the appropriate call to use either when the statement is 
   to executed a number of times with different arguments, and there
   is therefore a performance benefit to be had from preparing the 
   statement only once, or when the SQL statement is to contain 
   varying values taken from a source that cannot be completely trusted.
   In this latter case it may be unsafe to construct the SQL statement
   by simply concatenating the parts of the statement together, 
   since the values may contain pieces of SQL. 
   To guard against this, a so-called SQL injection attack,
   it is safer to prepare the SQL statement with placeholders 
   (also known as parameter markers, denoted by &#039;?&#039;) and supply a 
   list of the values to be substituted as a separate argument. 
   Otherwise this function is the same as 
   <span class="function"><strong>executeQuery()</strong></span> in that 
   it uses the model that it built from the metadata 
   to interpret the result set and returns a data graph.
  </p>
 </div>


 <div class="refsect1 parameters" id="refsect1-sdo-das-relational.executepreparedquery-parameters">
  <h3 class="title">参数</h3>
  <p class="para">
   <dl>

    
     <dt>
PDO_database_handle</dt>

     <dd>

      <p class="para">
       Constructed using the PDO extension. 
       A typical line to construct a PDO database handle might look 
       like this:
       <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
$dbh&nbsp;=&nbsp;new&nbsp;PDO("mysql:dbname=COMPANYDB;host=localhost",DATABASE_USER,DATABASE_PASSWORD);</span>
</code></div>
       </div>

      </p>
     </dd>

    
    
     <dt>
prepared_statement</dt>

     <dd>

      <p class="para">
       A prepared SQL statement to be executed against the database.
       This will have been prepared by PDO&#039;s
       <span class="function"><strong>prepare()</strong></span>
       method.
      </p>
     </dd>

    
    
     <dt>
value_list</dt>

     <dd>

      <p class="para">
       An array of the values to be substituted into the 
       SQL statement in place of the placeholders. In the event
       that there are no placeholders or parameter markers in the
       SQL statement then this argument can be specified as <strong><code>NULL</code></strong>
       or as an empty array; 
      </p>
     </dd>

    
    
     <dt>
column_specifier</dt>

     <dd>

      <p class="para">
       The Relational DAS needs to examine the result set and 
       for every column, know which table and which column of 
       that table it came from.
       In some circumstances it can find this information for itself, 
       but sometimes it cannot.
       In these cases a column specifier is needed, 
       which is an array that identifies the columns.
       Each entry in the array is simply a string in the form
       <var class="varname"><var class="varname">table-name.column_name</var></var>.
      </p>
          

      <p class="para">
       The column specifier is needed when there are duplicate 
       column names in the database metadata,
       For example, in the database used within the examples, 
       all the tables have both a
       <var class="varname"><var class="varname">id</var></var>
       and a
       <var class="varname"><var class="varname">name</var></var>
       column.
       When the Relational DAS fetches the result set from PDO 
       it can do so with the PDO_FETCH_ASSOC attribute, 
       which will cause the columns in the results set 
       to be labelled with  the column name, but will not distinguish 
       duplicates.
       So this will only work when there are no duplicates 
       possible in the results set.
      </p>
          
      <p class="para">
       To summarise, specify a column specifier array whenever there 
       is any uncertainty about which column could be from which table and
       only omit it when every column name in the database metadata is unique.
      </p>
          
      <p class="para">
       All of the examples in the
       <a href="sdodasrel.examples.html" class="link">Examples</a>
       use a column specifier.
       There is one example in the
       <var class="filename">Scenarios</var>
       directory of the installation that does not: 
       that which works with just the employee table, 
       and because it works with just one table, 
       there can not exist duplicate column names.
      </p>
     </dd>

    
   </dl>

  </p>
 </div>


 <div class="refsect1 returnvalues" id="refsect1-sdo-das-relational.executepreparedquery-returnvalues">
  <h3 class="title">返回值</h3>
  <p class="para">
   Returns a data graph. 
   Specifically, it returns a root object of a special type.
   Under this root object will be the data from the result set.
   The root object will have a multi-valued containment property 
   with the same name as the application root type 
   specified on the constructor,
   and that property will contain one or more data objects 
   of the application root type.
  </p>
  <p class="para">
   In the event that the query returns no data, 
   the special root object will still be returned but 
   the containment property for the application root type will be empty.
  </p>
 </div>


 <div class="refsect1 errors" id="refsect1-sdo-das-relational.executepreparedquery-errors">
  <h3 class="title">错误／异常</h3>
  <p class="para">
   <span class="function"><strong>SDO_DAS_Relational::executePreparedQuery()</strong></span>
   can throw an <strong class="classname">SDO_DAS_Relational_Exception</strong> if it is unable 
   to construct the data graph correctly.
   This can occur for a  number of reasons: 
   for example if it finds that it does not have primary keys 
   in the result set for all the objects.
   It also catches any PDO exceptions and obtains PDO 
   diagnostic information which it includes in an 
   <strong class="classname">SDO_DAS_Relational_Exception</strong> which it then throws.
  </p>
 </div>


 <div class="refsect1 examples" id="refsect1-sdo-das-relational.executepreparedquery-examples">
  <h3 class="title">范例</h3>
  <p class="para">
   <div class="example" id="example-5358">
    <p><strong>Example #1 Retrieving a data object using
    <span class="function"><strong>executePreparedQuery()</strong></span></strong></p>
    <div class="example-contents"><p>
     In this example a single data object is retrieved from the database 
     - or possibly more than one if there is more than one company 
     called &#039;Acme&#039;. For each company returned, the
     <var class="varname"><var class="varname">name</var></var>
     and
     <var class="varname"><var class="varname">id</var></var>
     properties are echoed.
    </p></div>
    <div class="example-contents"><p>
     Other examples of the use of 
     <span class="function"><strong>executePreparedQuery()</strong></span>
     can be found in the example code supplied in 
     <var class="filename">sdo/DAS/Relational/Scenarios</var>.
    </p></div>
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /></span><span style="color: #007700">require_once&nbsp;</span><span style="color: #DD0000">'SDO/DAS/Relational.php'</span><span style="color: #007700">;<br />require_once&nbsp;</span><span style="color: #DD0000">'company_metadata.inc.php'</span><span style="color: #007700">;<br /><br /></span><span style="color: #FF8000">/**************************************************************<br />&nbsp;*&nbsp;Construct&nbsp;the&nbsp;DAS&nbsp;with&nbsp;the&nbsp;metadata<br />&nbsp;***************************************************************/<br /></span><span style="color: #0000BB">$das&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">SDO_DAS_Relational&nbsp;</span><span style="color: #007700">(</span><span style="color: #0000BB">$database_metadata</span><span style="color: #007700">,</span><span style="color: #DD0000">'company'</span><span style="color: #007700">,</span><span style="color: #0000BB">$SDO_reference_metadata</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">/**************************************************************<br />&nbsp;*&nbsp;Get&nbsp;a&nbsp;database&nbsp;connection<br />&nbsp;***************************************************************/<br /></span><span style="color: #0000BB">$dbh&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">PDO</span><span style="color: #007700">(</span><span style="color: #0000BB">PDO_DSN</span><span style="color: #007700">,</span><span style="color: #0000BB">DATABASE_USER</span><span style="color: #007700">,</span><span style="color: #0000BB">DATABASE_PASSWORD</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">/**************************************************************<br />&nbsp;*&nbsp;Issue&nbsp;a&nbsp;query&nbsp;to&nbsp;obtain&nbsp;a&nbsp;company&nbsp;object&nbsp;-&nbsp;possibly&nbsp;more&nbsp;if&nbsp;they&nbsp;exist<br />&nbsp;*&nbsp;Use&nbsp;a&nbsp;prepared&nbsp;query&nbsp;with&nbsp;a&nbsp;placeholder.<br />&nbsp;***************************************************************/<br /></span><span style="color: #0000BB">$name&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #DD0000">'Acme'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$pdo_stmt&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$dbh</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">prepare</span><span style="color: #007700">(</span><span style="color: #DD0000">'select&nbsp;name,&nbsp;id&nbsp;from&nbsp;company&nbsp;where&nbsp;name=?'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$root&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$das</span><span style="color: #007700">-&gt;</span><span style="color: #0000BB">executePreparedQuery</span><span style="color: #007700">(<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$dbh</span><span style="color: #007700">,&nbsp;<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$pdo_stmt</span><span style="color: #007700">,<br />&nbsp;&nbsp;&nbsp;&nbsp;array(</span><span style="color: #0000BB">$name</span><span style="color: #007700">),&nbsp;<br />&nbsp;&nbsp;&nbsp;&nbsp;array(</span><span style="color: #DD0000">'company.name'</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">'company.id'</span><span style="color: #007700">));<br /><br /></span><span style="color: #FF8000">/**************************************************************<br />&nbsp;*&nbsp;Echo&nbsp;name&nbsp;and&nbsp;id&nbsp;<br />&nbsp;***************************************************************/<br /></span><span style="color: #007700">foreach&nbsp;(</span><span style="color: #0000BB">$root</span><span style="color: #007700">[</span><span style="color: #DD0000">'company'</span><span style="color: #007700">]&nbsp;as&nbsp;</span><span style="color: #0000BB">$company</span><span style="color: #007700">)&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;echo&nbsp;</span><span style="color: #DD0000">"Company&nbsp;obtained&nbsp;from&nbsp;the&nbsp;database&nbsp;has&nbsp;name&nbsp;=&nbsp;"&nbsp;</span><span style="color: #007700">.&nbsp;<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #0000BB">$company</span><span style="color: #007700">[</span><span style="color: #DD0000">'name'</span><span style="color: #007700">]&nbsp;.&nbsp;</span><span style="color: #DD0000">"&nbsp;and&nbsp;id&nbsp;"&nbsp;</span><span style="color: #007700">.&nbsp;</span><span style="color: #0000BB">$company</span><span style="color: #007700">[</span><span style="color: #DD0000">'id'</span><span style="color: #007700">]&nbsp;.&nbsp;</span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br />}<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

   </div>
  </p>
 </div>

</div><hr /><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="sdo-das-relational.createrootdataobject.html">SDO_DAS_Relational::createRootDataObject</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="sdo-das-relational.executequery.html">SDO_DAS_Relational::executeQuery</a></div>
 <div class="up"><a href="ref.sdodasrel.html">SDO-DAS-Relational 函数</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
